home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / contrib / partingr / README < prev    next >
Encoding:
Text File  |  1995-05-30  |  5.0 KB  |  149 lines  |  [TEXT/MPS ]
  1. This is plain TeX indexing and cross-reference support for noweb.
  2.  
  3. total 38
  4. -rwxr-x---  1 partingr      959 Aug  2 14:10 TeXthings
  5. -rwxr-x---  1 partingr     5544 Aug  2 14:19 addscore.nw
  6. -rwxr-xr-x  1 partingr     4672 Aug  2 13:35 mm2mx63
  7. -rwxr-xr-x  1 partingr     5033 Aug  2 13:35 mm2mx64
  8. -rwxr-xr-x  1 partingr     5180 Aug  2 13:35 mm2mx65
  9. -rwxr-xr-x  1 partingr     1445 Aug  2 13:37 mm2tex
  10. -rwxr-xr-x  1 partingr     4109 Aug  2 13:35 mx2tex31
  11. -rwxr-xr-x  1 partingr     4055 Aug  2 13:35 nwindex.tex
  12. -rwxr-x---  1 partingr       67 Aug  2 14:14 nwnweave
  13. -rwxr-xr-x  1 partingr       35 Aug  2 13:35 nwtangle
  14. -rwxr-xr-x  1 partingr       64 Aug  2 13:35 nwweave
  15. -rwxr-xr-x  1 partingr      524 Aug  2 13:58 xpand
  16.  
  17. This is what each file does/is:
  18.  
  19. TeXthings    perl 'header' file. needs to be somewhere
  20.         perl will find it when it executes mm2mx63
  21.         or mx2tex31 or mm2tex.
  22.  
  23. mm2mx63        version 6.3 of mm2mx. converts mm files
  24.         (those created by markup) into mx files
  25.         (which is my modified markup file).
  26.         sectionref macros are aaa,aab,aac,aad
  27.         reads from STDIN and outputs to STDOUT
  28.         see below for cli options.
  29.  
  30. mm2mx64        version 6.4 of mm2mx. virtually the same
  31.         as mm2mx63, but the sectionref macros that
  32.         get created have different names. default
  33.         is za,zc,zd etc. (I have lots of 2 character
  34.         macros for TeX so I don't use this so much,
  35.         but it might be useful...)
  36.  
  37. mm2mx65        same as mm2mx63, but converts @<name@> in
  38.         documentation chunks into a @use reference
  39.         so you get the reference style in the
  40.         documentation, if you see what I mean.
  41.         EG. "see @<main@>" will become
  42.         "see <main 1a>" if main is defined in 1a
  43.         (with the proper typesetting for the module
  44.         name of course).
  45.  
  46. mx2tex31    converts mx files into TeX. see below for
  47.         cli options.
  48.  
  49. mm2tex        weaver for normal markup files. tends to be
  50.         faster than awk because perl semi-compiles
  51.         it's programs before execution.
  52.  
  53. nwindex.tex    TeX macros for indexing.
  54.  
  55. nwnweave    shell script to weave a file with certain
  56.         cli options.
  57.  
  58. nwweave        shell script to weave a file with certain
  59.         cli options.
  60.  
  61. xpand        expands ...>> references in markup files.
  62.         !only *after* a full name has been seen!
  63.  
  64. CLI OPTIONS:
  65.  
  66. mm2mx63        -i    create an identifier index from @ %def lines
  67.         -m    create a module index
  68.         -n    case insensitive module name matching
  69.             (nb all module names come out in lower case)
  70.  
  71. mx2tex31    -i    create the indexes (from the mx file)
  72.         -n name    set the name of the output files. input is
  73.             from STDIN, output is to name.tex and
  74.             name.texnique.
  75.         -s    hack for 'only first definition gets the full
  76.                 list of defining chunks'.
  77.             (look at output to see the difference)
  78.         -f name    takes the markup file from name.markup and
  79.             outputs to name.tex and name.texnique
  80.         -h    help message
  81.         -q    no output to terminal at all
  82.  
  83. NWINDEX.MAC
  84.  
  85. When mx2tex31 creates a TeX file, it inserts 'hooks' into the code
  86. so that the chunk references can be printed out according to the
  87. user's preferences.
  88.  
  89. For all the hooks, \list contains a list of the defining chunks
  90. of the named chunk and \ulist contains a list of the chunks the
  91. named chunk is used in.
  92. (These lists are from Appendix D of The TeXBook. Items are
  93. seperated by \\ and contained in braces, so a list containing 1,2,3
  94. would be defined as \def\list{\\{1}\\{2}\\{3}}
  95.  
  96. For a chunk defined in 1a and 1b, and used in 1c
  97. \list={\\{1a}\\{1b}}
  98. \ulist={\\{1c}}
  99.  
  100. 3 hooks are provided...
  101.  
  102. \inmodname is called just before the right-angle of the chunk name
  103. \beforecode is called just after the chunk name (and angles) have
  104.             been set
  105. \aftercode is called just before \nwendcode{}
  106.  
  107. The default definitions:
  108. \inmodname = put the *first* defining chunk xref  in chunk names
  109. \beforecode = empty
  110. \aftercode = 'This definition is continued in section...' if the name
  111.                 is defined in more than one chunk and
  112.              'This code is used in section...'
  113.  
  114. [look at the output to see what happens]
  115. This gives output like the LaTeX cross-referencing (and like CWEB).
  116.  
  117. There are macros in nwindex.tex for printing out lists neatly
  118. (ie with commas and 'and' at the end) and for putting
  119. 'section' or 'sections' at the front of the list.
  120.  
  121. [if you need more info, either email me or wait for the documentation
  122.  which should be finished this week]
  123.  
  124. INDEXES
  125.  
  126. if asked to, mx2tex31 creates two files: name.ids and name.mods
  127. ids - identifier index
  128. mods - module index
  129.  
  130. It *doesn't* include these by default in the TeX file. you have
  131. to ask for them by putting \printindex{ids} or \printindex{mods}
  132.  
  133. you have to ask for them because (IMHO) indexes aren't vitally
  134. important while a program is being developed or for small
  135. programs.
  136.  
  137. the indexes are created in seperate files to allow other tools
  138. to create them independently of mx2tex31. for example, a
  139. c program could create name.ids by parsing the code chunks
  140. for identifiers etc. (like CWEB/WEB do) which would be a
  141. better way of indexing than @ %def lines...
  142.  
  143.  
  144. BTW I apologise for this documentation. I haven't had a
  145. chance to get a proper version written yet.
  146.  
  147. Do people want a TeXinfo version of the documentation or
  148. just plain TeX file?
  149.